Breaking Changes

This document explains several major changes that impact the Itential platform, especially when upgrading. For steps on how to upgrade your Itential software, see the Upgrade section of the admin guide.

BREAKING CHANGE for maintenance release 2018.3.21

The following are breaking changes for the 2018.3.21 maintenance release.

Important Note

It is the policy of Itential not to cause any breaking changes within the maintenance releases of a major release version; however, at times we have to do so and we extend our sincere apologies when those times occur. In this case, mitigating a security concern drives the need for this breaking change.

Replaced MongoDB Dependency for LocalAAA Adapter

Versions of IAP prior to the 2018.3.21 maintenance release contain a security vulnerability due to the Local AAA adapter's dependency on the MongoDB Node.js driver. Versions of MongoDB prior to 3.1.13 include a security vulnerability (Denial of Service). Consequently, that dependency was replaced with @itential/database, which requires a different set of database properties in the Local AAA service_config. Itential encourages everyone to install this patch to avoid the potential security risk.

The following is an example of the Local AAA service_config with database properties:

json { "id": "Local AAA", "type": "local_aaa", "properties": { "database": { "db": "LocalAAA", "url": "mongodb://mongo.example.com:27017/?replicaSet=rs_pronghorn", "ssl": { "enabled": true, "sslValidate": true, "sslCA": "/opt/data/mongodb/ssl/mongodb_rootCA.pem", "acceptInvalidCerts": false, "checkServerIdentity": true }, "replSet": { "enabled": true }, "credentials": { "dbAuth": true, "user": "<place_username_here>", "passwd": "<place_password_here" } } }, "brokers": [ "aaa" ] }

How to Configure Your Settings

Use the mongoProps settings from your environment to populate the settings object above within the LocalAAA service. Please note the db parameter must be set to "LocalAAA" as indicated above.

Itential only recommends the use of Local AAA adapter in non-production environments, which should further mitigate the impact of this change.

Breaking Changes in PH Core 6

Although Pronghorn (PH) Core 6.x provides new features, there are several breaking changes you must consider when upgrading the Itential Automation Platform (IAP) from Pronghorn Core 5.x to 6.x.

Node 8 is Required

All existing Pronghorn (Itential Automation Platform) implementations must upgrade to NodeJS 8.

Account, Group & Role APIs Removed/Replaced

The following APIs were removed because they are unable to support the richer Authorization Model in Pronghorn Core 6. With the richer model, the replacements listed are not direct replacements, but the closest analog. Moreover, the replacements do not represent the entirety of the new APIs around authorization structures.

Removed	Replacement	Notes
GET /config/users	GET /accounts
GET /config/user/:user	GET /accounts/:accountId
POST /config/user	PUT /accounts/:accountId
POST /config/new/user		Not Supported
POST /config/delete/user/:user		Not Supported
GET /config/groups	GET /groups
GET /config/group/:group	GET /groups/:groupId
POST /config/group	PUT /groups/:groupId	Only for PH Groups
POST /config/new/group	POST /groups	Only for PH Groups
POST /config/delete/group/:group	DELETE /groups/:groupId	Only for PH Groups
GET /config/roles	GET /roles

Note: Creating and deleting users are now functions of the AAA system. No attempt to expose those functions will be made by Pronghorn Core.

/whoAmI Schema Changed

For this schema:

• groups now contains objects including group id, name, and provenance, which will indicate the AAA provider from which the group is derive, or Pronghorn (IAP) in the case of Pronghorn Groups.
• roles are now prefixed by app export instead of app name.
• routes only contains allowed views.

The following non-breaking change was applied:

• Introduced provenance field, which will indicate the AAA provider from which the user is derived.

Audit Trail getUserObject() Schema Changed

For this schema:

• groups now contains objects including group id, name, and provenance, which will indicate the AAA provider from which the group is derived, or Pronghorn (IAP) in the case of Pronghorn Groups.

The following non-breaking change was applied:

• Introduced provenance field, which will indicate the AAA provider from which the user is derived.

Adapter Properties Schema is Required and Provider Properties are Validated at Load Time

For this schema:

• Adapters must now include a propertiesSchema.json file alongside the pronghorn.json. This file must be a valid JSON schema based on draft-06 or draft-07 and must indicate the JSON Schema version by use of the $schema keyword.
• Failure to include this will result in the adapter not being loaded, and an error will be printed in the pronghorn logs at startup.
• Individual Provider properties documents will be validated against the associated Adapter Properties Schema at Provider startup.
• Any validation failures will be logged and the Provider skipped (not loaded).

Note: Before upgrading, backup Mongo data and your /opt/pronghorn/current/properties.json file.

Corrected Workflow Engine Job Variable Validation

Versions of the Workflow Engine prior to the 2018.3.17 maintenance release contained a job variable validation flaw that prevented the user from being prompted for certain required job variables.

We have corrected this issue and now all required job variables must be supplied when a workflow is started, either from the UI or from the startJobWithOptionsAPI.

If your workflows contain either of the following two scenarios, you will need to correct the workflows before promoting this maintenance release to a production environment.

Please note that each scenario outlined below is now being properly validated.

1. The first scenario involves two tasks connected by a failure transition.

   

   The first task registers a job variable when the task errors.

   

   The second task (connected by a failure transition) is attempting to consume the job variable; however, since the task emitted an error instead of a failure, the job variable has never been set.

   

   Previously, the job would have started and failed if this particular transition were reached. Now that the job variable validation has been corrected, the job will not start without the variable provided as input.

   

   To correct this issue, review the transitions between the two tasks and assess the following solutions:

   Transition	Solution
   The transition was erroneously built as a failure transition instead of an error transition.	Change the transition to an error transition.
   The failure transition is correct and the job variable value should be provided by some other task in the workflow.	Identify the task that should provide the job variable value.
   Both the failure transition and the job variable were built correctly.	The job variable value will need to be provided by the initiator of the job.

2. The second scenario involves a task which self-references a job variable in both the input and error screens.

   

   The View Data task is consuming the job variable as input.

   

   The same job variable is produced by the task on the error transition.

   

   If this job variable is not defined anywhere else in the workflow, the validation should now properly fail and prompt the initiator to provide a value for the variable.

   

   To correct this issue, review the workflow for usage of this job variable. Identify the task that is meant to produce a value for the variable.

   If no such task exists, use the newVariable task to provide a default value for the variable.